feat(config): trim the public surface and add a compiled build (CLI-2234, CLI-2232) by Coly010 · Pull Request #6366 · supabase/cli

Coly010 · 2026-08-27T17:57:02Z

Closes CLI-2234
Closes CLI-2232

What changed

Prepares @supabase/config for its first npm publish: the export surface is audited and trimmed (CLI-2234) and the package gains a real compiled build (CLI-2232). One PR because the audit decides what the entrypoints contain and the build compiles exactly that, and the audit's type-surface enforcement (API report) only works once the build emits .d.ts.

Export-surface audit (CLI-2234)

Every export got an explicit keep / move / trim decision:

Decision	Symbols
Moved to `apps/cli`	`KONG_LOCAL_CA_CERT` (+ its test) — a local-stack TLS asset, not config schema
Moved to new `./internal` subpath (explicitly not semver-covered; enforced apps/cli-only)	`ENV_CAPTURE_REGEX`, `AUTH_HOOK_NAMES`, `unmappedSecretApiPaths`, `projectConfigMappingRows`, `ProjectConfigMappingRow`, `ProjectConfigApiAttributes`, `InternalLoadCliConfigOptions` + goViperCompat-capable typings of `loadCliConfig`/`resolveCliConfigValue`/`resolveCliConfigSubtree`
Removed from public options	`goViperCompat` (off `LoadCliConfigOptions`; resolvers lost their options param entirely — re-adding later is non-breaking)
Trimmed	`MissingCliConfigValueError` deleted entirely (never constructed anywhere in the package; apps/cli only carried a telemetry mapping entry + a test that fabricated one — both removed), `loadCliConfigFile`/`InternalResolveCliConfigOptions` off the internal barrel (zero consumers)
Renamed (`./io`, zero consumers existed)	`findCliProjectRootFor→findCliProjectRoot`, `findCliProjectPathsFor→findCliProjectPaths`, `loadCliProjectEnvironmentFor→loadCliProjectEnvironment`, `loadFunctionsManifest→inferFunctionsManifest` — `./io` now mirrors `./effect` 1:1; the subpath conveys Promise-vs-Effect
Added	sync `resolveCliConfigValue`/`resolveCliConfigSubtree` on `.` (Effect-typed variants deliberately shadow them on `./effect`); `ProjectConfigSchema` (runtime, Standard Schema v1 via `Schema.toStandardSchemaV1` — one symbol serves Effect-native and `~standard` consumers); `toProjectConfigJsonSchema`; `PROJECT_CONFIG_SCHEMA_URL`
Kept (documented contract in README)	schema/types, encoders, defaults + sparse helpers, the ProjectConfig converters (`toProjectConfig`, `fromConfigDocument`, `fromApiProjectConfig`, `attachApiResponse`, `comparableProjectConfigPaths`, `unmappedApiFields`), errors, functions-manifest model

ProjectConfigSchema is derived from CliConfigSchema at the AST level (hosted sections → type-side → deep-optional → x-secret leaves dropped → cross-field checks stripped, leaf checks kept) with a two-way compile-time assignability pin against the ProjectConfig type, so the runtime schema and the type cannot drift.

./io's error channel is narrowed from unknown to the exact five-member union (verified exact by review: no wider member, none unused).

Compiled build (CLI-2232)

Plain tsc (tsgo 7.0.2, nodenext + rewriteRelativeImportExtensions) emits ESM .js + .d.ts + maps to dist/; no bundler.
Conditional exports: in-repo Bun resolves src/*.ts (with customConditions: ["bun"] so tsc typechecks against source, not stale dist); external consumers get dist js + types.
Tarball sealed via files + .npmignore (npm-packlist otherwise applies the root .gitignore and ships no dist — npm pack and pnpm pack now agree); publish metadata (license, repository, publishConfig, engines) added; peers widened to >=4.0.0-rc.111 <5.
sideEffects: false, proven by a tree-shake probe with positive + negative controls against the built artifact.
dist/project-schema.json joins dist/schema.json (both draft-2020-12, now with $id/title, and with Effect's non-finite-number anyOf encoding collapsed so numeric fields keep description/default).
The docs site now publishes those same built artifacts verbatim (generate-docs.ts copies dist/*.json to apps/docs/public/cli/{config,project-config}.schema.json; docs generate dependsOn the package build) — one post-processed source of truth, and both $id URLs resolve once deployed.
Workspace test runners resolve the bun export condition (resolve.conditions/ssr.resolve.conditions in the vitest configs), so vitest exercises src — never a stale or absent dist (caught by the AI review: previously tests resolved the default → dist branch).
Build ends with a pack-and-install smoke test: real npm pack → temp install → real node imports every subpath.

Enforcement (surface changes stay deliberate)

Sealed exports map, pinned key set at runtime.
Per-entrypoint export-name snapshots (now incl. ./internal), purity walker over index.ts and io-browser.ts.
Type-surface changes: pnpm run check:config-api (root task; advisory continue-on-error CI step) emits declarations for the PR base and head — base source extracted via git archive into the package dir so the current install resolves deps, no second install — and reports the .d.ts diff in the job summary. Per-PR signal, zero committed artifacts. The hard gate moves to release time (CLI-2233): diff the new dist/*.d.ts against the previously published tarball's in the human-approval step.
@supabase/config/internal imports enforced apps/cli-only.

Review rounds

Three internal reviews (engineer, architect, DX-as-consumer incl. a clean-Node tarball install exercising 23 checks) ran before this PR; all accepted findings are in the final commit. Explicitly rejected, for the record:

@deprecated markers on ./internal exports (strikethrough noise across apps/cli's own legitimate call sites; the no-semver contract is documented at the barrel, README, and AGENTS.md).
message getters on the tagged error classes (would change CLI-visible error output pinned by normalize-error tests; README documents the structured-fields contract instead — candidate follow-up).
A checked-in api-report/ .d.ts mirror (53 files + freshness test) existed in earlier commits of this branch and was removed by owner decision — per-PR accept semantics weren't worth 580 KB of generated diff noise. Replaced by the advisory base-vs-head compare above; an api-extractor-style rollup was also considered and skipped (TS7/tsgo compatibility unproven).
saveCliConfig's atomic-write rename failure stays a defect (documented); re-channeling it as a typed failure is a behavioral follow-up.
Moving KONG_LOCAL_CA_CERT to packages/stack (single legacy consumer today; speculative second move).

Known collateral: `@supabase/pg-topo` under `customConditions`

customConditions: ["bun"] in apps/cli/tsconfig.json (needed so tsc typechecks @supabase/config against source instead of gitignored dist/) also changes resolution for @supabase/pg-topo, whose own bun exports condition points at unbuilt src/*.ts carrying 3 type errors at 1.0.0-alpha.5. Worked around with a commented paths pin to its shipped dist/index.d.ts. 1.0.0-alpha.6 is published but currently blocked by pnpm's minimumReleaseAge; once it ages in, bump it in apps/cli and drop the pin (and the bun-condition source errors deserve an upstream fix in supabase/pg-toolbelt either way).

Notes for CLI-2233 / CLI-2169 (publish)

The release pipeline must diff the new dist/*.d.ts against the previously published tarball's and surface that diff in the human-approval step — that is the hard semver gate (the PR-time compare above is advisory only; first publish trivially has no compare target).
Publish with pnpm publish (only pnpm rewrites any residual catalog:; peers are now literal ranges regardless).
effect@latest is still 3.x — README instructs effect@rc; revisit ranges when Effect 4 goes stable.
No top-level main/types (deliberate ESM + exports-only; node10 resolution unsupported).
Pre-existing @supabase/cli-go#lint:check gosec findings fail local check:all on clean develop too — untouched by this PR.

…cli (CLI-2234)

….json artifact (CLI-2234, CLI-2232)

…nd check in an API report (CLI-2232)

… (CLI-2234)

…-2232)

…onditions (CLI-2234)

github-actions · 2026-08-28T09:27:51Z

Superseded by a newer AI review

🤖 AI Review

This PR is too large for a full AI review (+10567/-520 lines across 118 files).

A maintainer can request a review anyway with a /ai-review comment.

github-actions · 2026-08-28T09:58:14Z

Superseded by a newer AI review

🤖 AI Review

This PR is too large for a full AI review (+10567/-520 lines across 118 files).

A maintainer can request a review anyway with a /ai-review comment.

…d declaration compare (CLI-2234)

github-actions

Superseded by a newer AI review

🤖 AI Review

Adjudicated 11 raw findings into 10 deduplicated findings: nine confirmed and one refuted. The most consequential issue is that unbuilt workspace tests can resolve @supabase/config to nonexistent dist files; the shallow-checkout API comparison and ProjectConfig primitive acceptance are also confirmed.

Findings

Severity	Location	Category	Sources	Claim
🟠 MAJOR	`packages/config/package.json:34`	`build-resolution`	claude	Workspace tests can resolve `.`, `./effect`, and `./internal` to nonexistent `dist` files because only the `bun` condition points to source and Vitest is not configured to request that condition.
🟡 MINOR	`tools/config-api-compare.ts:100`	`ci-correctness`	claude+codex	The API comparison fallback cannot reliably find a merge base from the workflow's depth-one checkout because it fetches only the base tip without deepening HEAD's history.
🟡 MINOR	`packages/config/src/internal.ts:21`	`api-contract`	claude	`InternalResolveCliConfigOptions` is repeatedly documented as exported from `@<!---->supabase/config/internal`, but that entrypoint does not export it.
🟡 MINOR	`packages/config/src/schema-metadata.ts:3`	`schema-publishing`	claude	`PROJECT_CONFIG_SCHEMA_URL` identifies a document that the docs generator never publishes, while the published CLI schema bypasses the post-processing applied to the packaged schema.
🟡 MINOR	`packages/config/src/project-config/project-schema.ts:151`	`validation`	codex	Object-shaped fields that become empty AST object nodes accept primitive values, so ProjectConfigSchema can validate values such as `db.vault: 42`.
⚪ NIT	`packages/config/src/errors.ts:135`	`documentation`	claude	Removing `MissingCliConfigValueError` leaves stale references to that symbol in the repository's root guidance documents.
⚪ NIT	`packages/config/scripts/json-schema-postprocess.ts:234`	`correctness`	claude	`withSchemaMetadata` allows pre-existing root `title` and `description` values to overwrite the metadata supplied by its caller.
⚪ NIT	`packages/config/scripts/build.ts:86`	`path-handling`	claude	JSON schema output paths are resolved from the process working directory rather than the package root used by the rest of the build.
⚪ NIT	`packages/config/AGENTS.md:120`	`documentation`	claude	The testing documentation says three contract tests exist but lists four bullets containing five test modules.

Refuted findings (kept for transparency, not posted as review comments)

apps/cli/tsconfig.json:12 (documentation): The customConditions: ["bun"] change silently affects @supabase/stack and @supabase/api in addition to the specifically named pg-topo package.
Refuted: The comment is deliberately general and explicitly warns that every other dependency declaring bun is affected; e.g. makes pg-topo non-exhaustive. Selecting the Bun variants is also consistent with this Bun-run CLI.

Stats

Claude findings: 9 · Codex findings: 2 · Confirmed: 9 · Refuted: 1 · Uncertain: 0

Models: claude-opus-5 + gpt-5.6-sol · Trigger: manual · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

…e on >=1 review (supabase#6380) Follow-up to the AI-review pipeline. Two changes. ## 1. Downgrade `codex-action` v1.12 → v1.11 On the large PR (supabase#6366, ~130k-token diff) the `codex-review` step ran to completion — Codex finished the turn, wrote its output file, printed its final message and token count — then **sat idle until the 45-minute job timeout**, discarding a completed review. That is a confirmed v1.12 regression: **openai/codex-action#150** ("v1.12: Linux run never returns after the turn completes; job dies on timeout with the output file already written"). The reporter confirms **v1.11 handles the same heavy workload cleanly**, and there is no released fix above v1.12. v1.11 (`52fe01ec…`) supports every input we use (`safety-strategy`, `sandbox`, `output-schema-file`, `output-file`, `codex-version`, `working-directory`, `effort`), so this is a drop-in pin change in both Codex jobs. ## 2. Adjudicate on ≥1 independent review (graceful degradation) Previously `adjudicate` required BOTH `claude-review` and `codex-review` to succeed, so one flaky model job sank the whole review. Now it runs when **at least one** independent pass succeeded: each findings download is guarded by its job's result, and the stage step substitutes an empty findings set for any review that didn't complete, so the adjudicator reconciles one or two. The prompt notes the one-review case and records it in its summary. Together: a Codex hiccup no longer wastes a 45-minute run or blocks Claude's (working) review from being posted.

…R (CLI-2234, CLI-2232)

github-actions

Superseded by a newer AI review

🤖 AI Review

Two documentation findings are confirmed. The packaging finding is refuted because the README explicitly says publication is deferred, while Claude's placeholder finding contains no verifiable claim and remains uncertain.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	`apps/cli/vitest.config.ts:25`	`testing`	claude	The submitted finding only claims "test" and does not identify a concrete defect.
🟡 MINOR	`packages/config/README.md:284`	`documentation`	codex	The documented `./io` error-handling contract gives contradictory and unusable type/message guidance.
⚪ NIT	`packages/config/README.md:265`	`documentation`	codex	The README incorrectly calls the two resolver functions the only non-Promise exports from `./io`.

Refuted findings (kept for transparency, not posted as review comments)

packages/config/package.json:4 (packaging): The package remains marked private, so npm will refuse to publish the newly prepared public package.
Refuted: The private flag is intentional for this PR. The newly added README explicitly documents deferred publication, and trusted/CLAUDE.md says internal TypeScript workspaces such as packages/config generally follow the private workspace template.

Stats

Claude findings: 1 · Codex findings: 3 · Confirmed: 2 · Refuted: 1 · Uncertain: 1

Models: claude-opus-5 + gpt-5.6-sol · Trigger: manual · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

…CLI-2234)

chatgpt-codex-connector · 2026-08-30T13:31:35Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-30T13:36:20.427211Z	`9872825`	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

github-actions · 2026-08-30T13:37:55Z

Supabase CLI preview

npx --yes https://pkg.pr.new/supabase/cli/supabase@98728256a07c47f5fba0710803d20106163759a0

Preview package for commit 9872825.

Coly010 added 6 commits August 27, 2026 16:24

refactor(config): trim CLI-internal exports into ./internal and apps/…

2ee7c34

…cli (CLI-2234)

feat(config): derive a runtime ProjectConfigSchema and project-schema…

ccc7e5d

….json artifact (CLI-2234, CLI-2232)

feat(config): compile dist JS and d.ts, seal the published tarball, a…

333489e

…nd check in an API report (CLI-2232)

docs(config): document the published contract and entrypoint surfaces…

e1aac36

… (CLI-2234)

fix(config): address publish-readiness review findings (CLI-2234, CLI…

7b96a61

…-2232)

fix(cli): pin pg-topo types to its shipped declarations under customC…

57945ae

…onditions (CLI-2234)

refactor(config): replace checked-in api-report with a CI base-vs-hea…

a2b0e35

…d declaration compare (CLI-2234)

Coly010 mentioned this pull request Aug 28, 2026

ci(repo): fix codex-action v1.12 hang (downgrade to v1.11), adjudicate on >=1 review #6380

Merged

github-actions Bot reviewed Aug 28, 2026

View reviewed changes

Coly010 mentioned this pull request Aug 28, 2026

ci(config): add independent release automation for @supabase/config (CLI-2233) #6381

Draft

fix(config): address AI review findings on the export-surface/build P…

8b9803b

…R (CLI-2234, CLI-2232)

github-actions Bot reviewed Aug 29, 2026

View reviewed changes

Comment thread apps/cli/vitest.config.ts

Comment thread packages/config/README.md Outdated

Comment thread packages/config/README.md Outdated

docs(config): correct the ./io error-contract and sync-export notes (…

9872825

…CLI-2234)

Coly010 self-assigned this Aug 30, 2026

Coly010 marked this pull request as ready for review August 30, 2026 13:31

Coly010 requested a review from a team as a code owner August 30, 2026 13:31

Navigation Menu

Uh oh!

feat(config): trim the public surface and add a compiled build (CLI-2234, CLI-2232) - #6366

feat(config): trim the public surface and add a compiled build (CLI-2234, CLI-2232)#6366
Coly010 wants to merge 9 commits into
developfrom
columferry/cli-2234-audit-and-trim-supabaseconfigs-public-export-surface-before

Coly010 commented Aug 27, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 28, 2026 •

edited

Loading

🤖 AI Review

Uh oh!

github-actions Bot commented Aug 28, 2026 •

edited

Loading

🤖 AI Review

Uh oh!

github-actions Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented Aug 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

Coly010 commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Export-surface audit (CLI-2234)

Compiled build (CLI-2232)

Enforcement (surface changes stay deliberate)

Review rounds

Known collateral: @supabase/pg-topo under customConditions

Notes for CLI-2233 / CLI-2169 (publish)

Uh oh!

github-actions Bot commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 AI Review

Uh oh!

github-actions Bot commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 AI Review

Uh oh!

github-actions Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

🤖 AI Review

Findings

Stats

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

🤖 AI Review

Findings

Stats

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented Aug 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Review Summary

Uh oh!

github-actions Bot commented Aug 30, 2026

Supabase CLI preview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Coly010 commented Aug 27, 2026 •

edited

Loading

Known collateral: `@supabase/pg-topo` under `customConditions`

github-actions Bot commented Aug 28, 2026 •

edited

Loading

github-actions Bot commented Aug 28, 2026 •

edited

Loading

github-actions Bot left a comment •

edited

Loading

github-actions Bot left a comment •

edited

Loading

chatgpt-codex-connector Bot commented Aug 30, 2026 •

edited

Loading